#ifndef __V_LIST_H__
#define __V_LIST_H__

#ifdef __cplusplus
extern "C" {
#endif

#include "../common/v_lib_type.h"

typedef struct vd_node  vd_list_node_t;
typedef struct vd_node* vd_list_it_ptr_t;   //迭代指针

struct vd_list {
    uint32_t list_size;
    uint32_t type_size;
    vd_list_node_t head;
    v_data_ptr_t null_data_ptr;     //空数据域,当容器容量为空时,头节点head数据域指针指向null_data_ptr
};

typedef struct vd_list  vd_list_t;
typedef struct vd_list* vd_list_ptr_t;      //容器指针

/**
 * @brief 创建一个链表容器
 *
 * @param type_size : 容器中元素类型的size
 *
 * @return 返回容器的地址
 */
vd_list_ptr_t vd_list_create(uint32_t type_size);

/**
 * @brief 删除一个链表容器
 *
 * @param list : 容器的地址
 *
 * @return NULL
 */
void vd_list_destroy(vd_list_ptr_t list);

/**
 * @brief 获取迭代元素的数据
 *
 * @param iter : 迭代指针
 *
 * @return 迭代数据的地址
 */
v_data_ptr_t vd_list_iter_data(vd_list_it_ptr_t iter);

/**
 * @brief 从前往后迭代1次
 *
 * @param iter : 迭代指针的地址
 *
 * @return NULL
 */
void vd_list_iter_forward(vd_list_it_ptr_t *iter);

/**
 * @brief 从前往后迭代n次
 *
 * @param iter : 迭代指针的地址
 * @param step : 迭代的次数
 *
 * @return NULL
 */
void vd_list_iter_forward_to(vd_list_it_ptr_t *iter, int step);

/**
 * @brief 从后往前迭代1次
 *
 * @param iter : 迭代指针的地址
 *
 * @return NULL
 */
void vd_list_iter_backward(vd_list_it_ptr_t *iter);

/**
 * @brief 从后往前迭代n次
 *
 * @param iter : 迭代指针的地址
 * @param step : 迭代的次数
 *
 * @return NULL
 */
void vd_list_iter_backward_to(vd_list_it_ptr_t *iter, int step);

/**
 * @brief 在position元素前插入一个元素
 *
 * @param list : 容器地址
 * @param position : 迭代指针
 * @param data_ptr : 插入元素的数据
 * @param data_size : 插入元素数据size
 *
 * @return NULL
 */
void vd_list_insert(vd_list_ptr_t list, vd_list_it_ptr_t position, vc_data_ptr_t data_ptr, uint32_t data_size);

/**
 * @brief 在容器尾部插入一个元素
 *
 * @param list : 容器地址
 * @param data_ptr : 插入元素的数据
 * @param data_size : 插入元素数据size
 *
 * @return NULL
 */
void vd_list_push_back(vd_list_ptr_t list, vc_data_ptr_t data_ptr, uint32_t data_size);

/**
 * @brief 在容器头部插入一个元素
 *
 * @param list : 容器地址
 * @param data_ptr : 插入元素的数据
 * @param data_size : 插入元素数据size
 *
 * @return NULL
 */
void vd_list_push_front(vd_list_ptr_t list, vc_data_ptr_t data_ptr, uint32_t data_size);

/**
 * @brief 删除容器尾部的元素
 *
 * @param list : 容器地址
 *
 * @return NULL
 */
void vd_list_pop_back(vd_list_ptr_t list);

/**
 * @brief 删除容器头部的元素
 *
 * @param list : 容器地址
 *
 * @return NULL
 */
void vd_list_pop_front(vd_list_ptr_t list);

/**
 * @brief 清空容器
 *
 * @param list : 容器地址
 *
 * @return NULL
 * 注意: 指针类型的容器慎用, 只将指针变量释放, 可能会造成内存泄露
 */
void vd_list_clear(vd_list_ptr_t list);

/**
 * @brief 获取容器最后一个元素数据
 *
 * @param list : 容器地址
 *
 * @return 最后一个元素数据地址
 */
v_data_ptr_t vd_list_back(vd_list_ptr_t list);

/**
 * @brief 获取容器第一个元素数据
 *
 * @param list : 容器地址
 *
 * @return 第一个元素数据地址
 */
v_data_ptr_t vd_list_front(vd_list_ptr_t list);

/**
 * @brief 获取容器第一个元素地址
 *
 * @param list : 容器地址
 *
 * @return 第一个元素地址
 */
vd_list_it_ptr_t vd_list_begin(vd_list_ptr_t list);

/**
 * @brief 获取容器最后一个元素地址
 *
 * @param list : 容器地址
 *
 * @return 最后一个元素地址
 */
vd_list_it_ptr_t vd_list_end(vd_list_ptr_t list);

/**
 * @brief 判断容器是否为空
 *
 * @param list : 容器地址
 *
 * @return true : 容器为空
 *         flase : 容器不为空
 */
bool vd_list_empty(vd_list_ptr_t list);

/**
 * @brief 获取容器元素个数
 *
 * @param list : 容器地址
 *
 * @return 元素个数
 */
uint32_t vd_list_size(vd_list_ptr_t list);

#ifdef __cplusplus
} /*extern "C"*/
#endif

#endif  /* __V_LIST_H__ */
